Incorporate "using crates from crates.io" into the main guide

Connects to rust-lang/cargo#1035. Using crates from crates.io is a
common thing that many people will want to know how to do right away and
deserves to be part of the main guide.

diff --git a/src/doc/crates-io.md b/src/doc/crates-io.md
index 7281c31c54155bb59da05615573c24313d4d4839..6914938a954cbf1742654ea96f10aa948321a719 100644 (file)
--- a/src/doc/crates-io.md
+++ b/src/doc/crates-io.md
@@ -1,35 +1,3 @@
-% Cargo and crates.io
-
-In addition to using dependencies from git repositories (as mentioned in
-[the guide](guide.html)) Cargo can also publish to and download from the
-[crates.io][crates-io] central repository. This site serves as a location to
-discover and download packages, and `cargo` is configured to use it by default
-to find requested packages.
-
-The guide will explain how crates can use crates.io through the `cargo` command
-line tool.
-
-[crates-io]: https://crates.io/
-
-# Using crates.io-based crates
-
-The method of specifying a dependency on a crate from crates.io is slightly
-different than the method of specifying a dependency on a git repository. The
-syntax for doing so is:
-
-```toml
-[dependencies]
-glob = "0.0.3"
-```
-
-With this format, adding new dependencies should just add a new line, you don’t
-need to add `[dependencies]` for each dependency listed, for example:
-
-```toml
-[dependencies]
-glob = "0.0.3"
-num = "0.0.4"
-```
 
 The string value for each key in this table is a [semver][semver] version
 requirement.
@@ -311,3 +279,5 @@ explicitly whitelisted crates.io querying the org in question by pressing
 the “Grant Access” button next to its name:
 
 ![Authentication Access Control](images/auth-level-acl.png)
+
+[crates-io]: https://crates.io/
\ No newline at end of file

diff --git a/src/doc/guide.md b/src/doc/guide.md
index f714a3956bcea9ec7ccbf1651dbf663690e58498..d3c79c5daf60a0c9fab6a7a436464b7655cf0e52 100644 (file)
--- a/src/doc/guide.md
+++ b/src/doc/guide.md
@@ -127,21 +127,35 @@ To build, use `cargo build`:
 This will fetch all of the dependencies and then build them, along with the
 project.
 
-# Adding Dependencies
+# Adding Dependencies from crates.io
 
-To depend on a library, add it to your `Cargo.toml`.
+[crates.io][crates-io] is the Rust community's central repository that serves
+as a location to discover and download packages. `cargo` is configured to use
+it by default to find requested packages.
+
+To depend on a library hosted on [crates.io], add it to your `Cargo.toml`.
+
+[crates-io]: https://crates.io/
 
 ## Adding a dependency
 
-It’s quite simple to add a dependency. Simply add it to your `Cargo.toml` file:
+If your `Cargo.toml` doesn't already have a `[dependencies]` section, add that,
+then list the crate name and version that you would like to use. This example
+adds a dependency of the `time` crate:
 
 ```toml
 [dependencies]
 time = "0.1.12"
 ```
 
-Re-run `cargo build` to download the dependencies and build your source with the new dependencies.
+The version string is a [semver][semver] version requirement.
+
+[semver]: https://github.com/steveklabnik/semver#requirements
 
+If we also wanted to add a dependency on the `regex` crate, we would not need
+to add `[dependencies]` for each crate listed. Here's what your whole
+`Cargo.toml` file would look like with dependencies on the `time` and `regex`
+crates:
 
 ```toml
 [package]
@@ -150,27 +164,12 @@ version = "0.1.0"
 authors = ["Your Name <you@example.com>"]
 
 [dependencies]
+time = "0.1.12"
 regex = "0.1.41"
 ```
 
-You added the `regex` library, which provides support for regular expressions.
-
-Now, you can pull in that library using `extern crate` in
-`main.rs`.
-
-```
-extern crate regex;
-
-use regex::Regex;
-
-fn main() {
-    let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap();
-    println!("Did our date match? {}", re.is_match("2014-01-01"));
-}
-```
-
-The next time we build, Cargo will fetch this new dependency, all of its
-dependencies, compile them all, and update the `Cargo.lock`:
+Re-run `cargo build`, and Cargo will fetch the new dependencies and all of
+their dependencies, compile them all, and update the `Cargo.lock`:
 
 <pre><code class="language-shell"><span class="gp">$</span> cargo build
 <span style="font-weight: bold" class="s1">    Updating</span> registry `https://github.com/rust-lang/crates.io-index`
@@ -188,18 +187,31 @@ dependencies, compile them all, and update the `Cargo.lock`:
 <span style="font-weight: bold" class="s1">   Compiling</span> regex v0.1.41
 <span style="font-weight: bold" class="s1">   Compiling</span> hello_world v0.1.0 (file:///path/to/project/hello_world)</code></pre>
 
-Run it:
-
-<pre><code class="language-shell"><span class="gp">$</span> cargo run
-<span style="font-weight: bold" class="s1">     Running</span> `target/hello_world`
-Did our date match? true</code></pre>
-
 Our `Cargo.lock` contains the exact information about which revision of all of
 these dependencies we used.
 
 Now, if `regex` gets updated, we will still build with the same revision until
 we choose to `cargo update`.
 
+You can now use the `regex` library using `extern crate` in `main.rs`.
+
+```
+extern crate regex;
+
+use regex::Regex;
+
+fn main() {
+    let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap();
+    println!("Did our date match? {}", re.is_match("2014-01-01"));
+}
+```
+
+Running it will show:
+
+<pre><code class="language-shell"><span class="gp">$</span> cargo run
+<span style="font-weight: bold" class="s1">     Running</span> `target/hello_world`
+Did our date match? true</code></pre>
+
 # Project Layout
 
 Cargo uses conventions for file placement to make it easy to dive into a new